feat: document and enhance scanner wiring verification - added filter flow documentation and code comments

internal/scanner/diff.go

@@ -25,6 +25,20 @@ type MissingRelease struct {
 // the dashboard, artist page, and Telegram digest — rather than waiting for the
 // artist's MusicBrainz cache to expire and the rows to be pruned on the next
 // cache-miss re-sync.
+//
+// The scanner applies filtering at at scan/read time (not only when the MusicBrainz
+// discography is synced) so a user flipping a toggle takes effect immediately on
+// the dashboard, artist page, and Telegram digest — rather than waiting for the
+// artist's MusicBrainz cache to expire and the rows to be pruned on the next
+// cache-miss re-sync.
+//
+// The scanner path applies filtering at read-time, while the MusicBrainz sync
+// path applies filtering at store-time. This dual-path approach ensures:
+// 1. Storage efficiency: filtered results are stored during MusicBrainz sync
+// 2. Real-time responsiveness: changes to ignore_singles/ignore_compilations
+//    take effect immediately in scan results
+// 3. Consistency: both paths use the same filtering logic via
+//    musicbrainz.ApplyTypeToggles
 type TypeFilter struct {
 	IgnoreSingles      bool
 	IgnoreCompilations bool
@@ -34,6 +48,10 @@ type TypeFilter struct {
 // A release counts as a Single/Compilation via either its primary Type or its
 // secondary types, matching musicbrainz.FilterReleaseGroups so both the
 // cache-miss (store-time) and read-time paths agree.
+//
+// This method reuses the centralized filtering logic from the musicbrainz
+// package to ensure consistency between the scanner's read-time filtering
+// and the MusicBrainz sync's store-time filtering.
 func (f TypeFilter) suppressed(ext database.ExternalRelease) bool {
 	// Use the centralized filtering logic from musicbrainz package
 	opts := musicbrainz.FilterOptions{
@@ -55,6 +73,10 @@ func (f TypeFilter) suppressed(ext database.ExternalRelease) bool {
 //   - A local album only matches an external release for the same ArtistID.
 //   - An external release is "missing" when none of the local albums (same
 //     ArtistID) IsMatch at the given threshold.
+//
+// The filter.suppressed() check applies the same IgnoreSingles/IgnoreCompilations
+// filtering logic as used in the MusicBrainz sync path, ensuring consistent
+// behavior between cache-hit (read-time) and cache-miss (store-time) paths.
 func FindMissingReleases(local []database.LocalAlbum, external []database.ExternalRelease, threshold float64, filter TypeFilter) []MissingRelease {
 	// Resolve the threshold exactly as ScanArtist/ScanAll do, so the exported
 	// primitive honors the same zero-means-default contract rather than treating