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/dbq/discover.sql.go

@@ -15,7 +15,7 @@ const listCrossUserLikedTracksForDiscover = `-- name: ListCrossUserLikedTracksFo
 SELECT t.id, t.album_id, t.artist_id
   FROM general_likes gl
   JOIN tracks t ON t.id = gl.track_id
- WHERE t.missing_since IS NULL   -- #2523: never offer a file that is gone
+ WHERE t.missing_since IS NULL   -- never offer a file that is gone
    AND gl.user_id != $1
    AND NOT EXISTS (
        SELECT 1 FROM play_events pe
@@ -55,8 +55,8 @@ type ListCrossUserLikedTracksForDiscoverRow struct {
 //
 // GROUP BY (not SELECT DISTINCT) so the md5 ORDER BY expression need
 // not appear in the select list — Postgres rejects DISTINCT + ORDER BY
-// by-expression at plan time (SQLSTATE 42P10), which previously caused
-// the entire Discover build to fail silently.
+// by-expression at plan time (SQLSTATE 42P10), which would fail the
+// entire Discover build.
 func (q *Queries) ListCrossUserLikedTracksForDiscover(ctx context.Context, arg ListCrossUserLikedTracksForDiscoverParams) ([]ListCrossUserLikedTracksForDiscoverRow, error) {
 	rows, err := q.db.Query(ctx, listCrossUserLikedTracksForDiscover, arg.UserID, arg.Column2)
 	if err != nil {
@@ -96,7 +96,7 @@ dormant_artists AS (
 SELECT t.id, t.album_id, t.artist_id
   FROM tracks t
   JOIN dormant_artists da ON da.id = t.artist_id
- WHERE t.missing_since IS NULL   -- #2523: never offer a file that is gone
+ WHERE t.missing_since IS NULL   -- never offer a file that is gone
    AND NOT EXISTS (
        SELECT 1 FROM play_events pe
         WHERE pe.user_id = $1
@@ -161,7 +161,7 @@ func (q *Queries) ListDormantArtistTracksForDiscover(ctx context.Context, arg Li
 const listRandomUnheardTracksForDiscover = `-- name: ListRandomUnheardTracksForDiscover :many
 SELECT t.id, t.album_id, t.artist_id
   FROM tracks t
- WHERE t.missing_since IS NULL   -- #2523: never offer a file that is gone
+ WHERE t.missing_since IS NULL   -- never offer a file that is gone
    AND NOT EXISTS (
        SELECT 1 FROM play_events pe
         WHERE pe.user_id = $1
@@ -223,7 +223,7 @@ WITH scored AS (
       FROM tracks t
       JOIN LATERAL regexp_split_to_table(coalesce(t.genre, ''), '[;,]') AS g_split(g) ON true
       JOIN taste_profile_tags nt ON nt.user_id = $3 AND trim(g_split.g) = nt.tag
-     WHERE t.missing_since IS NULL   -- #2523: never offer a file that is gone
+     WHERE t.missing_since IS NULL   -- never offer a file that is gone
        AND nt.weight > 0
        AND trim(g_split.g) <> ''
        AND NOT EXISTS (
@@ -274,7 +274,7 @@ type ListTasteUnheardTracksForDiscoverRow struct {
 }
 
 // Taste-targeted novelty: unheard tracks whose genres overlap the user's
-// taste-profile tags (taste_profile_tags, #796), ranked by summed tag
+// taste-profile tags (taste_profile_tags), ranked by summed tag
 // weight — "new to you, but your vibe" rather than the crude random arm.
 // Genres live inline on tracks.genre as a delimited string, split the
 // same way the radio tag_overlap arm does (regexp_split_to_table on
@@ -282,13 +282,13 @@ type ListTasteUnheardTracksForDiscoverRow struct {
 // when the user has no taste tags yet (cold start), so the caller
 // redistributes its slots to the other buckets. Stamped 'taste_unheard'.
 //
-// The per-album and per-artist caps apply BEFORE the LIMIT (#5356). Summed
-// weight rewards a track for carrying many of the user's tags, so a few
-// artists whose every track is tagged with the whole profile take every row
-// of a plain LIMIT; the caller's caps then left 6 of 120 on the deploy, and
-// the best-performing arm handed its slots to the others. Ranking within
-// album, then within artist over what the album cap kept, is the same walk
-// capByAlbumAndArtist makes, so the caller's caps keep everything here.
+// The per-album and per-artist caps apply BEFORE the LIMIT. Summed weight
+// rewards a track for carrying many of the user's tags, so a few artists
+// whose every track is tagged with the whole profile would take every row of
+// a plain LIMIT, the caller's caps would then leave a handful, and the arm
+// would hand its slots to the others. Ranking within album, then within
+// artist over what the album cap kept, is the same walk capByAlbumAndArtist
+// makes, so the caller's caps keep everything here.
 func (q *Queries) ListTasteUnheardTracksForDiscover(ctx context.Context, arg ListTasteUnheardTracksForDiscoverParams) ([]ListTasteUnheardTracksForDiscoverRow, error) {
 	rows, err := q.db.Query(ctx, listTasteUnheardTracksForDiscover,
 		arg.MaxPerArtist,