refactor(feed): add comments explaining ad placeholder injection

- Added comments in HeadlinesFeedBloc to clarify the process of injecting
  ad placeholders in different feed loading scenarios.
- Explained that the full ad loading and lifecycle are managed by the UI layer.
- Provided references to FeedDecoratorService for more detailed explanations
  of the ad architecture and feed decoration pipeline.

Author: fulleni

lib/headlines-feed/bloc/headlines_feed_bloc.dart

@@ -111,6 +111,9 @@ class HeadlinesFeedBloc extends Bloc<HeadlinesFeedEvent, HeadlinesFeedState> {
       );
 
       // For pagination, only inject ad placeholders, not feed actions.
+      // This method injects stateless `AdPlaceholder` markers into the feed.
+      // The full ad loading and lifecycle is managed by the UI layer.
+      // See `FeedDecoratorService` for a detailed explanation.
       final newProcessedFeedItems =
           await _feedDecoratorService.injectAdPlaceholders(
         feedItems: headlineResponse.items,
@@ -164,7 +167,9 @@ class HeadlinesFeedBloc extends Bloc<HeadlinesFeedEvent, HeadlinesFeedState> {
           ? await _userContentPreferencesRepository.read(id: currentUser!.id)
           : null;
 
-      // For a major load, use the full decoration pipeline.
+      // For a major load, use the full decoration pipeline, which includes
+      // injecting a high-priority decorator and stateless ad placeholders.
+      // See `FeedDecoratorService` for a detailed explanation of the ad architecture.
       final decorationResult = await _feedDecoratorService.decorateFeed(
         headlines: headlineResponse.items,
         user: currentUser,
@@ -249,6 +254,9 @@ class HeadlinesFeedBloc extends Bloc<HeadlinesFeedEvent, HeadlinesFeedState> {
           ? await _userContentPreferencesRepository.read(id: currentUser!.id)
           : null;
 
+      // Use the full decoration pipeline, which includes injecting a
+      // high-priority decorator and stateless ad placeholders.
+      // See `FeedDecoratorService` for a detailed explanation of the ad architecture.
       final decorationResult = await _feedDecoratorService.decorateFeed(
         headlines: headlineResponse.items,
         user: currentUser,
@@ -329,6 +337,9 @@ class HeadlinesFeedBloc extends Bloc<HeadlinesFeedEvent, HeadlinesFeedState> {
           ? await _userContentPreferencesRepository.read(id: currentUser!.id)
           : null;
 
+      // Use the full decoration pipeline, which includes injecting a
+      // high-priority decorator and stateless ad placeholders.
+      // See `FeedDecoratorService` for a detailed explanation of the ad architecture.
       final decorationResult = await _feedDecoratorService.decorateFeed(
         headlines: headlineResponse.items,
         user: currentUser,