Document using an EventSourcedBehavior as a PersistentFSM (#27931)

Re-uses the code from the migration guide as the mgiration logic
is in adapters.

Almost seems very obvious you can do this but can't hurt to have.

* Apply suggestions from code review

Co-Authored-By: Helena Edelson <helena@users.noreply.github.com>

akka-docs/src/main/paradox/typed/index-persistence.md

@@ -12,6 +12,7 @@ project.description: Event Sourcing with Akka Persistence enables actors to pers
 * [persistence-style](persistence-style.md)
 * [persistence-snapshot](persistence-snapshot.md)
 * [persistence-testing.md](persistence-testing.md)
+* [persistence-fsm.md](persistence-fsm.md)
 * [persistence-schema-evolution](../persistence-schema-evolution.md)
 * [persistence-query](../persistence-query.md)
 * [persistence-query-leveldb](../persistence-query-leveldb.md)

akka-docs/src/main/paradox/typed/persistence-fsm.md

@@ -0,0 +1,57 @@
+# EventSourced behaviors as finite state machines
+
+An @apidoc[EventSourcedBehavior] can be used to represent a persistent FSM. If you're migrating an existing classic
+persistent FSM to EventSourcedBehavior see the @ref[migration guide](../persistence-fsm.md#migration-to-eventsourcedbehavior).
+
+To demonstrate this consider an example of a shopping application. A customer can be in the following states:
+
+* Looking around
+* Shopping (has something in their basket)
+* Inactive
+* Paid
+
+Scala
+:  @@snip [PersistentFsmToTypedMigrationSpec.scala](/akka-persistence-typed/src/test/scala/docs/akka/persistence/typed/PersistentFsmToTypedMigrationSpec.scala) { #state }
+
+Java
+:  @@snip [PersistentFsmToTypedMigrationCompileOnlyTest.java](/akka-persistence-typed/src/test/java/jdocs/akka/persistence/typed/PersistentFsmToTypedMigrationCompileOnlyTest.java) { #state }
+
+
+And the commands that can result in state changes:
+
+* Add item
+* Buy
+* Leave 
+* Timeout (internal command to discard abandoned purchases)
+
+And the following read only commands:
+
+* Get current cart 
+
+Scala
+:  @@snip [PersistentFsmToTypedMigrationSpec.scala](/akka-persistence-typed/src/test/scala/docs/akka/persistence/typed/PersistentFsmToTypedMigrationSpec.scala) { #commands }
+
+Java
+:  @@snip [PersistentFsmToTypedMigrationCompileOnlyTest.java](/akka-persistence-typed/src/test/java/jdocs/akka/persistence/typed/PersistentFsmToTypedMigrationCompileOnlyTest.java) { #commands }
+
+The command handler of the EventSourcedBehavior is used to convert the commands that change the state of the FSM
+to events, and reply to commands.
+
+@scala[The command handler:]@java[The `forStateType` command handler can be used:]
+
+Scala
+:  @@snip [PersistentFsmToTypedMigrationSpec.scala](/akka-persistence-typed/src/test/scala/docs/akka/persistence/typed/PersistentFsmToTypedMigrationSpec.scala) { #command-handler }
+
+Java
+:  @@snip [PersistentFsmToTypedMigrationCompileOnlyTest.java](/akka-persistence-typed/src/test/java/jdocs/akka/persistence/typed/PersistentFsmToTypedMigrationCompileOnlyTest.java) { #command-handler }
+
+The event handler is used to change state once the events have been persisted. When the EventSourcedBehavior is restarted
+the events are replayed to get back into the correct state.
+
+Scala
+:  @@snip [PersistentFsmToTypedMigrationSpec.scala](/akka-persistence-typed/src/test/scala/docs/akka/persistence/typed/PersistentFsmToTypedMigrationSpec.scala) { #event-handler }
+
+Java
+:  @@snip [PersistentFsmToTypedMigrationCompileOnlyTest.java](/akka-persistence-typed/src/test/java/jdocs/akka/persistence/typed/PersistentFsmToTypedMigrationCompileOnlyTest.java) { #event-handler }
+
+