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

internal/musicbrainz/sync.go

@@ -57,6 +57,15 @@ func SyncArtistDiscography(
 	// ignore_singles / ignore_compilations take effect without waiting for cache
 	// expiry. (Status/type inclusion was already applied when the rows were first
 	// synced and stored, so only the toggles can change.)
+	//
+	// The MusicBrainz sync path applies filtering at store-time (when caching
+	// release groups from the API), while the scanner path applies filtering at
+	// read-time (when retrieving cached data). This dual-path approach ensures:
+	// 1. Storage efficiency: filtered results are stored, reducing database size
+	// 2. Real-time responsiveness: changes to ignore_singles/ignore_compilations
+	//    take effect immediately without waiting for cache expiry
+	// 3. Consistency: both paths use the same filtering logic via
+	//    musicbrainz.ApplyTypeToggles
 	if fresh {
 		if err := ctx.Err(); err != nil {
 			return nil, fmt.Errorf("sync artist discography: %w", err)