docs: query comments say what each query selects and why, not how it came to be (#6277)

Rewrites the internal/db/queries comments to rule 32 and regenerates
dbq, whose doc comments and embedded SQL carry them. The bugs behind the
tiered mixes, the md5 order seed, the score bands and the round-robin
arms are restated as the constraint each one enforces; counts from one
library and stale cross-references are gone.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

internal/db/queries/albums.sql

@@ -37,12 +37,12 @@ ORDER BY release_date NULLS LAST, sort_title;
 
 -- name: GetAlbumByArtistAndTitle :one
 -- Scanner uses this for the no-mbid dedupe path: resolve-or-create. An album
--- of the same name in another release group is a different album (Weezer's
--- six self-titled albums shared one row until 2026-10-20), so a row whose
+-- of the same name in another release group is a different album (one
+-- artist's self-titled albums), so a row whose
 -- group is known and differs is not returned. A row of the file's own group
 -- comes first, then one with no group yet, then the one holding the most
 -- tracks from the file's folder: a file tagged with no group (a live bonus
--- track beside Weezer's 1994 album) belongs with its folder, not the oldest
+-- track beside its album) belongs with its folder, not the oldest
 -- row, and a few strays already misfiled do not outvote the folder.
 SELECT albums.* FROM albums
  WHERE albums.artist_id = sqlc.arg(artist_id) AND albums.title = sqlc.arg(title)
@@ -79,12 +79,10 @@ SELECT * FROM albums ORDER BY random() LIMIT $1;
 -- Album "belongs to" a genre if any of its tracks carry that genre.
 -- Serves Subsonic getAlbumList?type=byGenre.
 --
--- Splits tracks.genre on [;,] as of #367. It previously compared the whole
--- column verbatim, so a track tagged "Rock;Pop" was unreachable from EITHER
--- "Rock" or "Pop" — a Subsonic client asking for a genre silently missed
--- every multi-genre track. This also aligns the endpoint with
--- recommendation.sql / discover.sql, which have always split, and with the
--- genre browse index that #367 adds.
+-- Splits tracks.genre on [;,], so a track tagged "Rock;Pop" is reachable from
+-- both "Rock" and "Pop"; comparing the whole column would hide every
+-- multi-genre track from a Subsonic client asking for a genre. The same split
+-- as recommendation.sql, discover.sql and the genre browse index.
 --
 -- EXISTS rather than JOIN + DISTINCT ON: the lateral split emits one row per
 -- (track, genre-fragment), so a join would multiply rows per album and lean
@@ -111,7 +109,7 @@ LIMIT $2 OFFSET $3;
 SELECT COUNT(*) FROM albums WHERE title ILIKE '%' || $1::text || '%';
 
 -- name: ListRecentlyAddedAlbumsWithArtist :many
--- M6a: recently-added albums joined with artist_name + artist_id for the
+-- Recently-added albums joined with artist_name + artist_id for the
 -- home-page section. created_at is the row-insert timestamp from the
 -- scanner — the closest proxy to "added to library". Stable secondary
 -- ordering by id keeps pagination tie-break deterministic.
@@ -122,7 +120,7 @@ ORDER BY albums.created_at DESC, albums.id
 LIMIT $1;
 
 -- name: ListAlbumsAlphaWithArtist :many
--- M6a: alpha-sorted album list joined with artist_name. Used by
+-- Alpha-sorted album list joined with artist_name. Used by
 -- /api/library/albums for the wrapping-grid page. Stable id-tiebreak.
 SELECT sqlc.embed(albums), artists.name AS artist_name
 FROM albums
@@ -131,7 +129,7 @@ ORDER BY albums.sort_title, albums.id
 LIMIT $1 OFFSET $2;
 
 -- name: CountAlbums :one
--- M6a: total album count for the /api/library/albums envelope.
+-- Total album count for the /api/library/albums envelope.
 SELECT COUNT(*) FROM albums;
 
 -- name: CountAlbumsByArtist :one
@@ -140,7 +138,7 @@ SELECT COUNT(*) FROM albums;
 SELECT COUNT(*) FROM albums WHERE artist_id = $1;
 
 -- name: DeleteAlbumIfEmpty :one
--- M7 #372: deletes the album row only when it has no remaining tracks.
+-- Deletes the album row only when it has no remaining tracks.
 -- Used after a track delete to tidy up orphaned albums. RETURNING gives
 -- us the artist_id so the service can chain into the artist-empty check.
 -- Returns no rows when the album still has tracks; the service treats
@@ -151,7 +149,7 @@ WHERE a.id = $1
 RETURNING a.id, a.artist_id;
 
 -- name: SetAlbumMbidIfNull :exec
--- M7 #379: heal MBID on existing album rows during rescan. Idempotent —
+-- Heal MBID on existing album rows during rescan. Idempotent —
 -- only updates when the existing mbid is NULL.
 UPDATE albums
    SET mbid = $2,
@@ -159,7 +157,7 @@ UPDATE albums
  WHERE id = $1 AND mbid IS NULL;
 
 -- name: SetAlbumReleaseGroupMbidIfNull :exec
--- #5241: heal the release-group id on an existing album row, from a rescan's
+-- Heal the release-group id on an existing album row, from a rescan's
 -- tags or from the re-acquisition sweeper's MusicBrainz lookup. Only fills a
 -- NULL, so a tag never gets overwritten by a later guess or vice versa.
 UPDATE albums
@@ -168,7 +166,7 @@ UPDATE albums
  WHERE id = $1 AND release_group_mbid IS NULL;
 
 -- name: GetReleaseGroupForReleaseMbid :one
--- #5241: the release group the library already knows for a release id, so a
+-- The release group the library already knows for a release id, so a
 -- request carrying a release id can be repaired without asking MusicBrainz.
 SELECT release_group_mbid::text
   FROM albums
@@ -176,7 +174,7 @@ SELECT release_group_mbid::text
  LIMIT 1;
 
 -- name: SetReleaseGroupForReleaseMbidIfNull :exec
--- #5241: cache a MusicBrainz-resolved release group onto the album row that
+-- Cache a MusicBrainz-resolved release group onto the album row that
 -- holds the release, filling only a NULL.
 UPDATE albums
    SET release_group_mbid = sqlc.arg(release_group_mbid)::text,
@@ -188,7 +186,7 @@ UPDATE albums
 -- one of its tracks' file_path so the worker can re-read tags. LIMIT
 -- supplied by caller for batching/progress purposes. The track read is
 -- one still on disk; an album with none left is skipped until a scan
--- finds its files again (#5139).
+-- finds its files again.
 SELECT a.id          AS album_id,
        a.artist_id   AS artist_id,
        a.title       AS title,
@@ -207,7 +205,7 @@ SELECT a.id          AS album_id,
  LIMIT $1;
 
 -- name: GetAlbumCoverageRollup :one
--- M7 coverage-gauge: library-wide cover-art coverage rollup for the
+-- Library-wide cover-art coverage rollup for the
 -- admin gauge. Single sequential scan with FILTER aggregates —
 -- sub-millisecond on realistic libraries. pending_no_mbid is a SUBSET
 -- of pending; the UI surfaces it separately so operators can see how
@@ -217,12 +215,9 @@ SELECT a.id          AS album_id,
 -- Invariant: with_art + pending + settled = total. (pending_no_mbid is
 -- not part of the sum — it's a subset of pending, surfaced separately.)
 --
--- The IN list below must stay in sync with the cover_art_source CHECK
--- constraint — currently relaxed by migration 0020 to include 'deezer'
--- and 'lastfm', and migration 0030 further relaxed it to any non-empty
--- string. If a new source value is added without updating this query,
--- with_art will silently undercount. Drift #556 caught the deezer +
--- lastfm omission introduced by migration 0020.
+-- The IN list below must name every source the enrichers write (the
+-- cover_art_source CHECK accepts any non-empty string since migration
+-- 0030). A source missing here makes with_art silently undercount.
 SELECT
   COUNT(*)                                                                   AS total,
   COUNT(*) FILTER (WHERE cover_art_source IN
@@ -233,7 +228,7 @@ SELECT
 FROM albums;
 
 -- name: SetAlbumCoverWithVersion :exec
--- M7 cover-sources: records a successful or settled enrichment with the
+-- Records a successful or settled enrichment with the
 -- current sources_version stamp. cover_art_path is NULL when source is
 -- 'none' (no file written). Atomic; called per album per pass.
 UPDATE albums
@@ -246,5 +241,5 @@ UPDATE albums
 
 -- name: GetAlbumsByIDs :many
 -- Batched lookup used by /api/library/sync to hydrate upsert payloads
--- (#357). Mirror of GetArtistsByIDs.
+--. Mirror of GetArtistsByIDs.
 SELECT * FROM albums WHERE id = ANY($1::uuid[]);