feat(query): add Query, MustQuery, and UpdateOne helpers

Adds scan-into-dest query helpers and update-one-row semantics with
Context variants, tests, and documentation updates.

Co-authored-by: Cursor <cursoragent@cursor.com>

query_test.go

@@ -91,3 +91,45 @@ func TestMustFetchOne_NotFound(t *testing.T) {
 	assert.Nil(t, result)
 	assert.ErrorIs(t, err, errNotFound)
 }
+
+func TestQuery_ScansDest(t *testing.T) {
+	stmt := mockStatement{
+		queryContextFn: func(_ context.Context, dest any) error {
+			ptr := dest.(*row)
+			ptr.ID = 5
+			return nil
+		},
+	}
+
+	var result row
+	err := Query(mockQueryable{}, stmt, &result)
+	require.NoError(t, err)
+	assert.Equal(t, 5, result.ID)
+}
+
+func TestMustQuery_NotFound(t *testing.T) {
+	errNotFound := errors.New("not found")
+	stmt := mockStatement{
+		queryContextFn: func(_ context.Context, _ any) error {
+			return ErrNoRows
+		},
+	}
+
+	var result row
+	err := MustQuery(mockQueryable{}, stmt, &result, errNotFound)
+	assert.ErrorIs(t, err, errNotFound)
+}
+
+func TestMustQueryContext_PropagatesContext(t *testing.T) {
+	ctx := context.WithValue(context.Background(), testContextKey{}, "ok")
+	var gotCtx context.Context
+	stmt := mockStatement{
+		queryContextFn: func(c context.Context, dest any) error {
+			gotCtx = c
+			return ErrNoRows
+		},
+	}
+
+	_ = MustQueryContext(ctx, mockQueryable{}, stmt, &row{}, errors.New("nf"))
+	assert.Equal(t, ctx, gotCtx)
+}