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/browse.sql

@@ -1,29 +1,23 @@
--- Every query in this file filters `tracks.missing_since IS NULL` (#2523).
--- A row whose file has vanished keeps its genre forever — the scanner walks the
--- filesystem, so it never revisits a path that no longer exists — which is how
--- pre-#2499 welded genres survived a full re-scan and kept showing in the index.
--- Browsing is a way of finding something to play, so a track that cannot play
+-- Every query in this file filters `tracks.missing_since IS NULL`. A row whose
+-- file has vanished keeps its genre forever — the scanner walks the
+-- filesystem, so it never revisits a path that no longer exists — and
+-- browsing is a way of finding something to play, so a track that cannot play
 -- should not shape it.
 --
--- The year axis filters too (#2702). It used to join albums only, on the
--- reasoning that an album is a real release even when some of its tracks are
--- gone — true, but it left the two browse axes disagreeing: the genre queries
--- above filter tracks.missing_since, so an album whose every file had vanished
--- was already absent from genre while still listed under its year, where
--- opening it found nothing playable.
+-- The year axis filters too, so the two axes agree: an album whose every file
+-- has vanished is absent from both, rather than absent from its genre and
+-- still listed under its year, where opening it would find nothing playable.
 --
--- Hiding is the answer rather than showing-and-marking because browsing is how
--- you go looking for something to play, and the operator's rule for that case
--- is to take it out of view; the admin missing-files surface is where absence
--- is reported. It also means changing the axis that was inconsistent rather
--- than the one that was already right.
+-- Hiding rather than showing-and-marking, because browsing is how you go
+-- looking for something to play; the admin missing-files surface is where
+-- absence is reported.
 --
 -- The predicate is "has at least one playable track", so it also excludes an
 -- album with no tracks at all. That is the same answer for the same reason:
 -- nothing to play, nothing to browse to.
 
 -- name: ListGenresWithCount :many
--- Genre browse index (#367).
+-- Genre browse index.
 --
 -- Genres live inline on tracks.genre as a delimited string, so this splits on
 -- the same [;,] pattern already used by recommendation.sql and discover.sql —
@@ -34,14 +28,14 @@
 -- trim() but deliberately NO lower(): trimming repairs an artifact of OUR
 -- splitting ("Rock; Pop" yields " Pop", and showing that as a distinct genre
 -- would be a bug), whereas case is what the tag actually says. Raw ID3 is
--- exposed as-is for v1, so "Rock" and "rock" appear as separate rows.
+-- exposed as-is, so "Rock" and "rock" appear as separate rows.
 --
 -- COUNT(DISTINCT) because a sloppy tag like "Rock;Rock" would otherwise
 -- inflate its own row.
 --
 -- Ordered by count first: raw ID3 data has a long tail of one-off junk tags,
--- so alphabetical would bury the handful of genres an operator actually has a
--- library's worth of. Name breaks ties for a stable order.
+-- so alphabetical would bury the handful of genres a library actually has
+-- a lot of. Name breaks ties for a stable order.
 SELECT trim(g.genre) AS genre, COUNT(DISTINCT tracks.id)::bigint AS track_count
 FROM tracks
 JOIN LATERAL regexp_split_to_table(coalesce(tracks.genre, ''), '[;,]') AS g(genre) ON true
@@ -87,7 +81,7 @@ WHERE EXISTS (
 );
 
 -- name: ListAlbumYearsWithCount :many
--- Year browse index (#367). Only albums with a release_date appear — an
+-- Year browse index. Only albums with a release_date appear — an
 -- album with no date isn't "year unknown" as a browsable bucket, it's absent
 -- from this axis, and the UI says so rather than inventing a 0 row.
 -- Newest first: recent releases are the likelier browse target.
@@ -132,8 +126,7 @@ WHERE release_date IS NOT NULL
 -- name: ListGenresForAlbum :many
 -- Distinct genres carried by an album's tracks, for the album detail page's
 -- quick-jump chips. Split and trimmed identically to ListGenresWithCount, so a
--- chip always leads to a page that actually contains this album — the two
--- diverging is exactly the bug #367 had to fix in ListAlbumsByGenre.
+-- chip always leads to a page that actually contains this album.
 SELECT DISTINCT trim(g.genre) AS genre
 FROM tracks
 JOIN LATERAL regexp_split_to_table(coalesce(tracks.genre, ''), '[;,]') AS g(genre) ON true