docs: wanted, dbtest, recommendation and playlists comments say what the code does (#6277)

The same rewrite as d191a282, for four packages whose comments carried the
most history: tuning stories, quotes from the operator, single-install
measurements in library_scale.go, and 'used to' accounts of bugs. The
constraint each story protected stays as a present-tense reason (why tier 3
is reduced not removed, why the randomised arms take an order seed, why the
seed artist is eligible in Songs-like). Comments naming system_cron.go and
config.RecommendationConfig, neither of which holds what they claimed, now
name the scheduler and internal/recsettings.

Checked: non-comment tokens identical to HEAD; gofmt clean.

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

internal/dbtest/reset.go

@@ -1,10 +1,9 @@
 // Package dbtest provides shared helpers for integration tests that need
-// a clean Postgres state without disturbing the operator's admin user.
+// a clean Postgres state without disturbing the developer's admin user.
 //
-// Background: when integration tests run against the same Postgres
-// instance an operator uses for local dev (a common dev-laptop setup),
-// a TRUNCATE that includes the users table wipes the operator's admin
-// login between every test run. To avoid that, tests should:
+// When integration tests run against the same Postgres a developer uses
+// for local dev, a TRUNCATE that includes the users table wipes their admin
+// login on every test run. To avoid that, tests should:
 //
 //  1. Call ResetDB instead of issuing TRUNCATE statements directly. It
 //     truncates every data table EXCEPT users, then deletes only those
@@ -40,8 +39,8 @@ const TestUserPrefix = "test-"
 var dataTables = []string{
 	"artist_similarity",
 	"track_similarity",
-	"artist_similarity_unmatched",     // M5c
-	"listenbrainz_similar_recordings", // #5296
+	"artist_similarity_unmatched",
+	"listenbrainz_similar_recordings",
 	"track_similarity_fetches",
 	"artist_similarity_fetches",
 	"scrobble_queue",
@@ -55,13 +54,13 @@ var dataTables = []string{
 	"sessions",
 	"quarantine_actions",
 	"quarantine",
-	// #2374. Keyed by (user_id, candidate_mbid) with no FK to artists —
+	// Keyed by (user_id, candidate_mbid) with no FK to artists —
 	// candidates are out-of-library — so the CASCADE from artists/users
 	// does NOT reach it for a leftover row whose user survived. Truncate
 	// explicitly or a stale snooze silently hides a candidate from the
 	// next test's suggestion assertions.
 	"suggestion_snoozes",
-	// #2376. Same reasoning: keyed by candidate MBID with no FK anywhere,
+	// Same reasoning: keyed by candidate MBID with no FK anywhere,
 	// so nothing cascades to them. A leftover tag row would make a
 	// candidate look enriched to the next test, and a leftover state row
 	// would make it look already-settled and thus ineligible.
@@ -69,7 +68,7 @@ var dataTables = []string{
 	"candidate_artist_tag_state",
 	"playlist_tracks",
 	"playlists",
-	"library_changes", // M7 #357 — must reset to keep cursor isolated per test
+	"library_changes", // reset so each test's sync cursor starts clean
 	// SettingsService.reconcile() idempotently re-UpsertProviderSettings
 	// for every registered provider at boot, so truncating this is the
 	// correct per-test reset (clears test-modified enabled/api_key rows).
@@ -77,46 +76,46 @@ var dataTables = []string{
 	// (never recreates the singleton, seeded once by 0018); ResetDB
 	// resets its counter via UPDATE below instead.
 	"cover_art_provider_settings",
-	// Same reasoning for the tag-enrichment settings (#1490): truncate the
+	// Same reasoning for the tag-enrichment settings: truncate the
 	// per-provider rows (reconcile re-seeds registered ones), and reset the
 	// tag_sources_meta counter via UPDATE below rather than truncating it.
 	"tag_provider_settings",
-	// recsettings.New reconciles shipped defaults on every construction
-	// (#1250), so truncating gives each test pristine tuning values.
+	// recsettings.New reconciles shipped defaults on every construction,
+	// so truncating gives each test pristine tuning values.
 	"recommendation_weight_profiles",
 	"taste_tuning",
-	// #2377. Same reasoning as taste_tuning above: recsettings.New re-seeds
+	// Same reasoning as taste_tuning above: recsettings.New re-seeds
 	// shipped defaults on every construction, so truncating gives each test
 	// pristine Discover knobs rather than whatever a previous test tuned.
 	"discover_tuning",
 	"recommendation_tuning_audit",
-	"duplicate_group_members", // M400
+	"duplicate_group_members",
 	"duplicate_groups",
 	"duplicate_sweeps",
-	"track_fingerprints",       // M400
-	"track_loudness",           // M464
-	"album_loudness",           // M464
-	"user_normalization_prefs", // M464
-	// M489. Both cascade from users, but the operator's own admin row is
+	"track_fingerprints",
+	"track_loudness",
+	"album_loudness",
+	"user_normalization_prefs",
+	// Both cascade from users, but the developer's own admin row is
 	// never deleted, so rows a test wrote for it would otherwise survive.
 	"user_notifications",
 	"user_notification_prefs",
-	"user_notification_email_state", // #5346
-	"acquisition_services",          // M502 #5518
-	"mb_release_tracks",             // M502 #5519
-	"mb_releases",                   // M502 #5519
-	"mb_artist_release_groups",      // M502 #5519
-	"mb_release_groups",             // M502 #5519
-	"mb_artists",                    // M502 #5519
-	"requests",                      // M502 #5520
-	"download_interventions",        // M502 #5523
-	"library_album_matches",         // #5569
-	"release_blocks",                // M502 #5521
-	"grabs",                         // M502 #5521
-	"want_candidates",               // M502 #5521
-	"wants",                         // M502 #5520
-	"follow_seen_groups",            // M502 #5520
-	"follows",                       // M502 #5520
+	"user_notification_email_state",
+	"acquisition_services",
+	"mb_release_tracks",
+	"mb_releases",
+	"mb_artist_release_groups",
+	"mb_release_groups",
+	"mb_artists",
+	"requests",
+	"download_interventions",
+	"library_album_matches",
+	"release_blocks",
+	"grabs",
+	"want_candidates",
+	"wants",
+	"follow_seen_groups",
+	"follows",
 	"tracks",
 	"albums",
 	"artists",
@@ -124,7 +123,7 @@ var dataTables = []string{
 
 // ResetDB clears all data tables and removes any user whose username
 // begins with TestUserPrefix. Users without that prefix (notably the
-// operator's admin row) are left alone. Calls t.Fatalf on error.
+// developer's admin row) are left alone. Calls t.Fatalf on error.
 func ResetDB(t *testing.T, pool *pgxpool.Pool) {
 	t.Helper()
 	ctx := context.Background()
@@ -148,7 +147,7 @@ func ResetDB(t *testing.T, pool *pgxpool.Pool) {
 	); err != nil {
 		t.Fatalf("dbtest.ResetDB reset cover-art version: %v", err)
 	}
-	// Same for the tag-sources counter (#1490) — clears cross-test version
+	// Same for the tag-sources counter — clears cross-test version
 	// accumulation that would spuriously report version_bumped on a
 	// key-only change.
 	if _, err := pool.Exec(ctx,
@@ -156,7 +155,7 @@ func ResetDB(t *testing.T, pool *pgxpool.Pool) {
 	); err != nil {
 		t.Fatalf("dbtest.ResetDB reset tag-sources version: %v", err)
 	}
-	// Fingerprinting settings (M400 #3913), a singleton like the counters above.
+	// Fingerprinting settings, a singleton like the counters above.
 	// Every column goes back to its migration default rather than to literals
 	// written here, so a test can pin the Go defaults to the migration's.
 	if _, err := pool.Exec(ctx, `
@@ -167,14 +166,14 @@ func ResetDB(t *testing.T, pool *pgxpool.Pool) {
 	); err != nil {
 		t.Fatalf("dbtest.ResetDB reset fingerprint settings: %v", err)
 	}
-	// Loudness analysis settings (M464 #4995), reset the same way.
+	// Loudness analysis settings, reset the same way.
 	if _, err := pool.Exec(ctx, `
 		UPDATE loudness_settings
 		   SET enabled = DEFAULT, backfill_concurrency = DEFAULT, updated_at = DEFAULT`,
 	); err != nil {
 		t.Fatalf("dbtest.ResetDB reset loudness settings: %v", err)
 	}
-	// Release-type profiles (M502 #5520): migration 0081 seeds "Standard" as
+	// Release-type profiles: migration 0081 seeds "Standard" as
 	// the default. Tests add and edit profiles, so put back exactly the
 	// seeded row rather than truncating it away.
 	if _, err := pool.Exec(ctx, `
@@ -185,8 +184,8 @@ func ResetDB(t *testing.T, pool *pgxpool.Pool) {
 	); err != nil {
 		t.Fatalf("dbtest.ResetDB reset release-type profiles: %v", err)
 	}
-	// Search and grab settings (M502 #5521), a singleton reset the same way.
-	// The library listing (#5567) reads as done, so a test's albums are not
+	// Search and grab settings, a singleton reset the same way.
+	// The library listing reads as done, so a test's albums are not
 	// put on the wanted list behind its back; its own tests clear it.
 	if _, err := pool.Exec(ctx, `
 		UPDATE acquisition_settings
@@ -197,7 +196,7 @@ func ResetDB(t *testing.T, pool *pgxpool.Pool) {
 	); err != nil {
 		t.Fatalf("dbtest.ResetDB reset acquisition settings: %v", err)
 	}
-	// Notification email settings (M489 #5346), reset the same way.
+	// Notification email settings, reset the same way.
 	if _, err := pool.Exec(ctx, `
 		UPDATE notification_email_settings
 		   SET summary_hour = DEFAULT, batch_window_minutes = DEFAULT, updated_at = DEFAULT`,