docs(material/button): document iconPositionEnd and matButtonIcon attributes (#32822)

Add an "Icon positioning" section to the button documentation
explaining how icons are projected within buttons using content
projection selectors:

- Default behavior: icons appear before the label
- iconPositionEnd: places an icon after the label
- matButtonIcon: marks custom elements for icon projection

These attributes have been supported since the MDC migration but
were never documented.

Closes #26259

Author: yogeshwaran-c

src/material/button/button.md

@@ -43,6 +43,47 @@ the `extended` attribute, mini FABs do not.
 </button>
 ```
 
+### Icon positioning
+
+Buttons can contain icons alongside text. By default, icons (`mat-icon`, `.material-icons`, or
+elements with the `matButtonIcon` attribute) are projected **before** the button label.
+
+```html
+<button matButton>
+  <mat-icon>favorite</mat-icon>
+  Like
+</button>
+```
+
+To place an icon **after** the button label, add the `iconPositionEnd` attribute to the icon element:
+
+```html
+<button matButton>
+  Send
+  <mat-icon iconPositionEnd>send</mat-icon>
+</button>
+```
+
+You can also use both positions at once:
+
+```html
+<button matButton>
+  <mat-icon>arrow_back</mat-icon>
+  Navigate
+  <mat-icon iconPositionEnd>arrow_forward</mat-icon>
+</button>
+```
+
+If you are using a custom icon element that is not a `mat-icon` or `.material-icons`, add the
+`matButtonIcon` attribute so that the button can project it into the correct slot:
+
+```html
+<button matButton>
+  <my-custom-icon matButtonIcon>custom</my-custom-icon>
+  Action
+</button>
+```
+
 ### Interactive disabled buttons
 Native disabled `<button>` elements cannot receive focus and do not dispatch any events. This can
 be problematic in some cases because it can prevent the app from telling the user why the button is