docs: api comments say what the endpoints do, not how they came to be (#6277)

Rewrites the internal/api comment blocks to rule 32: task, milestone and
rule ids gone, the stories behind them restated as the constraint they
left, stale references corrected (the stream secret is wired from config,
the timezone handler already refreshes the scheduler, the Android app is
the native client, the design docs cited are not in the repo). Also
rewraps comment lines over 80 columns left by the earlier batches.

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

internal/api/events.go

@@ -22,16 +22,16 @@ type eventRequest struct {
 	At               *string `json:"at"`
 	ClientID         *string `json:"client_id"`
 	// Source tags which surface a play_started came from. "for_you"
-	// / "discover" feed the system-playlist rotation dedup (#415);
+	// / "discover" feed the system-playlist rotation dedup;
 	// absent / "" for library, user-playlist, radio, Subsonic.
 	Source *string `json:"source"`
-	// DeviceClass is the client's self-reported device class (#1551),
+	// DeviceClass is the client's self-reported device class,
 	// normalized + stored per play to condition radio on the current device.
 	DeviceClass *string `json:"device_class"`
 }
 
 // knownDeviceClasses whitelists the device classes the context-affinity facet
-// buckets by (#1551). A client sends one; anything unrecognized normalizes to
+// buckets by. A client sends one; anything unrecognized normalizes to
 // "other", and empty/absent to "" (stored NULL → excluded from the device
 // dimension). Kept permissive (no DB CHECK) so a new client class is one
 // whitelist entry, not a migration.
@@ -66,9 +66,9 @@ const eventFutureSkew = 5 * time.Minute
 // clampEventTime bounds a client-supplied event timestamp to sanity:
 // no earlier than the account's creation (offline replays can
 // legitimately be days old, but no play can predate the user) and no
-// later than now + a small skew allowance. Unbounded client clocks
-// previously let a skewed device write arbitrarily old plays, which
-// poisoned Rediscover's "not played in 6 months" ordering (#1246).
+// later than now + a small skew allowance. An unbounded client clock would
+// let a skewed device write arbitrarily old plays, poisoning Rediscover's
+// "not played in 6 months" ordering.
 func clampEventTime(at, userCreatedAt, now time.Time) time.Time {
 	if at.Before(userCreatedAt) {
 		return userCreatedAt
@@ -157,11 +157,11 @@ func (h *handlers) handleEventPlayStarted(
 }
 
 // handleEventPlayOffline records a complete play that happened with
-// no/flaky connectivity, replayed from the Flutter offline mutation
-// queue (#426 part B). `at` is the original (client) play-start time
-// — parsed by handleEvents from req.At — so history lands on the
-// real timeline, not replay time. duration_played_ms drives the skip
-// rule; source advances #415 rotation for system-playlist plays.
+// no or flaky connectivity, replayed from a client's offline queue.
+// `at` is the original (client) play-start time — parsed by handleEvents
+// from req.At — so history lands on the real timeline, not replay time.
+// duration_played_ms drives the skip rule; source advances the
+// system-playlist rotation.
 func (h *handlers) handleEventPlayOffline(
 	w http.ResponseWriter, r *http.Request,
 	user dbq.User, req eventRequest, at time.Time, clientID string,